<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Configuring: GNOME Data Access 5 manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GNOME Data Access 5 manual">
<link rel="up" href="installation.html" title="Installation">
<link rel="prev" href="compiling.html" title="Compiling your code using the Libgda library">
<link rel="next" href="getting_started.html" title="Code examples">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="installation.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="compiling.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="getting_started.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="sect1">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="installation-configuring"></a>Configuring</h2></div></div></div>
<p>
      Depending on the use you're going to get out of <span class="application">Libgda</span>, you may have
      to dig deep into its internals, but don't be afraid, things have been
      implemented to be easy to use.
    </p>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="installation-development"></a>Configuration for development</h3></div></div></div>
<p>
        If you want to develop applications using <span class="application">Libgda</span>, you should 
        install the libgda-dev[el] package if you do a <a href="http://foldoc.org/RPM"><span class="acronym">RPM</span></a> or Debian-based
        installation. If you compiled the source code, development files are
        installed in your system.
      </p>
<p>
        The only step you need to do to make sure everything is well 
        installed, is to check that <span class="application">Libgda</span> libraries and binaries are seen
        by your system. That is, make sure that the <span class="application">Libgda</span> 
        <code class="filename">bin/</code> directory is in your
        <code class="envar">PATH</code> environment variable, as well as the
        <code class="filename">lib/</code> in your 
        <code class="envar">LD_LIBRARY_PATH</code> (or 
        <code class="filename">/etc/ld.so.conf</code> file).
      </p>
<p>
        Programs which need to use <span class="application">Libgda</span>'s features need to include headers files, which are:
      </p>
<pre class="programlisting">
#include &lt;libgda/libgda.h&gt;
#include &lt;sql-parser/gda-sql-parser.h&gt;
      </pre>
      and to use reports:
      <pre class="programlisting">
#include &lt;libgda/libgda.h&gt;
#include &lt;libgda-report/libgda-report.h&gt;
      </pre>
      and to use virtual connections:
      <pre class="programlisting">
#include &lt;libgda/libgda.h&gt;
#include &lt;virtual/libgda-virtual.h&gt;
      </pre>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="installation-client"></a>Configuration for accessing a database</h3></div></div></div>
<p>
	To access a database, it must have a database provider (if <span class="application">Libgda</span> does not
	support the type of database to access, make a bug report in 
	<a class="ulink" href="http://bugzilla.gnome.org/" target="_top">bugzilla</a>), and that database provider
	must be compiled an installed: the <span class="command"><strong>gda-list-config-5.0</strong></span> or 
	<span class="command"><strong>gda-sql-5.0 -L</strong></span> commands will
	show a list of the installed and configured database providers.
      </p>
<p>
	Any connection to a database can be done either using a pre-defined data source, or using a
	connection string: using a data source (DSN) allows one to <span class="emphasis"><em>name</em></span> connections
	and define them once, whereas using connection strings allows programs to be more
	independent of any <span class="application">Libgda</span> configuration. Anyway, defining a DSN involves defining the same
	parameters as for a connection string.
      </p>
<p>
	A connection string is a semi-colon delimited list of named parameters 
	(as &lt;param1_name&gt;=&lt;param1_value&gt;;&lt;param2_name&gt;=&lt;param2_value&gt;...), the parameters
	being specific to each database provider (the two commands mentioned above also list all the
	parameters for each provider).
      </p>
<p>
	DSNs can be configured on a per-user basis or on a system-wide basis. Each user's
	own DSN definitions are stored in the <code class="filename">$HOME/.local/share/libgda/config</code> file
	(which
	is created the first time <span class="application">Libgda</span> is used within an application. System wide DSN are defined in the
	<code class="filename">&lt;prefix&gt;/etc/libgda/config</code>. Rather than editing that
	file manually, it is possible to use the <span class="command"><strong>gda-control-center-5.0</strong></span> tool
	(part of <span class="application">Libgda</span>).
	Note: if the <code class="filename">$HOME/.libgda/config</code> already exists from a previous use
	of <span class="application">Libgda</span>, then that file is used instead of
	<code class="filename">$HOME/.local/share/libgda/config</code>.
      </p>
</div>
<div class="sect2">
<div class="titlepage"><div><div><h3 class="title">
<a name="installation-provider"></a>Provider's specific information</h3></div></div></div>
<p>
        This section provides information specific to each of the available
        <span class="application">Libgda</span> providers.
      </p>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="installation-provider-default"></a>SQLite provider</h4></div></div></div>
<p>
	  The SQLite provider is always installed (it is required by <span class="application">Libgda</span>'s internally)
          with <span class="application">Libgda</span>, which means that a default database system is always available. 
	  Specifically the first time you use
	  <span class="application">Libgda</span>, a test database is copied into <code class="filename">$HOME/.local/share/libgda/config</code>
	  (or <code class="filename">$HOME/.libgda</code> if it exists and <code class="filename">$HOME/.local/share/libgda/config</code>
	  does not)
	  named "SalesTest". 
	</p>
</div>
<div class="sect3">
<div class="titlepage"><div><div><h4 class="title">
<a name="installation-provider-all"></a>Connection information for each database provider</h4></div></div></div>
<p>
	  Each provider exports a list of the arguments it requires in 
	  its connection string which is used internally by <span class="application">Libgda</span> to
	  establish each connection. To obtain the required information to open a connection
	  using a provider, use the <a class="link" href="gda-sql.html" title="Part VII. Gda SQL console's user manual">Gda SQL console tool</a> with the
	  <strong class="userinput"><code>-L &lt;provider name&gt;</code></strong> option. For example for PostgreSQL (strings truncated
	  for better readability):
	  </p>
<pre class="programlisting">
<code class="systemitem">$ </code>gda-sql -L PostgreSQL
                   Provider 'PostgreSQL' description
Attribute      | Value                                                   
---------------+-------------------------------------------------------------
Provider       | PostgreSQL                                              
Description    | Provider for PostgreSQL databases                       
DSN parameters | DB_NAME: The name of a database to connect to (string),     
                 SEARCHPATH: Search path among database's schemas ('search_path' variable) (string),
                 HOST: Host on which the database server is running (for servers running on unix domain sockets, enter the socket's path (usually /tmp), or leave this field empty).
                 PORT: Database server port (for servers running on unix domain sockets, enter the socket's file name extension (usually 5432), or leave this field empty).
                 OPTIONS: Extra connection options (string),                 
                 USE_SSL: Whether or not to use SSL to establish the connection (boolean),
Authentication | USERNAME (string),                                                         
                 PASSWORD (string)
File           | /local/lib/libgda-4.0/providers/libgda-postgres.so
(5 rows)
	  </pre>
<p>
	</p>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>